---
title: Inventory
---

## Overview

In Spree each Variant has a `StockItem`. This is the place where the inventory for that variant is stored. Variant can have multiple `StockItems` if they are available in multiple `StockLocations`.

Back-ordered, sold, or shipped products are stored as individual `InventoryUnit` objects so they can have relevant information attached to them.

New products created in the system can be given a starting "on hand" inventory level. You can subsequently set new inventory levels and the correct things will happen, e.g. adding new on-hand inventory to an out-of-stock product that has some backorders will first fill the backorders then update the product with the remaining inventory count.

## Inventory Management

### Stock Locations

Stock Locations are the locations where your inventory is shipped from. Each `StockLocation` has many `stock_items` and `stock_movements`.

Stock Locations can be created in the admin panel Configuration → Stock Locations or via Platform API.

Stock Locations have several attributes that define their properties and behavior within the Spree system. Below is a table outlining these attributes:

| Attribute         | Description                                                                 | Example Value       |
|-------------------|-----------------------------------------------------------------------------|---------------------|
| `name`            | The public name of the stock location. This is used on Storefront and Storefront API | Warehouse 1       |
| `admin_name`       | The name used internally for the stock location. This is not shown on the Storefront. | WH1 Domestic     |
| `address1`        | The primary address line for the stock location.                           | 5th avenue     |
| `address2`        | The secondary address line for the stock location.                         | Suite 100         |
| `city`            | The city where the stock location is based.                                | New York        |
| `state_id`        | The ID of the state where the stock location is based. This references the `State` model. | 1                 |
| `country_id`      | The ID of the country where the stock location is based. This references the `Country` model. | 1                 |
| `zipcode`         | The postal code for the stock location.                                    | 10001             |
| `phone`           | The contact phone number for the stock location.                           | 555-1234          |
| `active`          | A boolean indicating whether the stock location is active. Inactive stock locations will not be used in stock calculations or be available for selection during checkout. | `true`             |
| `default`          | A boolean indicating whether the stock location is the default one used for new inventory operations. | `false`             |
| `backorderable_default` | A boolean indicating whether new stock items in this location are backorderable by default. | `false` |
| `propagate_all_variants` | A boolean indicating whether new stock items should be automatically created for all Store variants when a new stock location is added. | `false` |

Stock Locations can be easily used for tracking warehouses and other physical locations. They can be used to track separate sections of a warehouse (e.g. aisles, shelves, etc.) or to track different warehouses.

You can easily use them with your Point of Sale (POS) system to track inventory at different locations.

### Stock Items

Stock Items represent the inventory at a stock location for a specific variant. Stock item count on hand can be increased or decreased by creating stock movements.

| Attribute         | Description                                                                 | Example Value       |
|-------------------|-----------------------------------------------------------------------------|---------------------|
| `stock_location_id` | References the stock location where the stock item belongs.                | `1`                 |
| `variant_id`      | References the variant associated with the stock item.                     | `32`                |
| `count_on_hand`   | The number of items available on hand.                                     | `150`               |
| `backorderable`   | Indicates whether the stock item can be backordered.                       | `true`    |

### Stock Transfers

Stock transfers allow you to move inventory in bulk from one stock location to another stock location. This is handy when you want to integrate with a POS system or other inventory management system. Or you can just rely on Spree being the source of truth for your inventory.

<Info>
Stock Transfers can be created in the Admin dashboard or via the Platform API.
</Info>

Here's the list of attributes for the Stock Transfer model:

| Attribute                | Description                                                                 | Example Value       |
|--------------------------|-----------------------------------------------------------------------------|---------------------|
| `number`                 | The unique number identifier for the stock transfer, generated automatically. | `T123456789`        |
| `reference`              | An optional reference field for the stock transfer.                        | Transfer for Event |
| `source_location_id`     | The ID of the stock location where the stock is transferred from.          | `2`                 |
| `destination_location_id`| The ID of the stock location where the stock is transferred to.            | `3`                 |

Stock transfers are crucial for managing inventory across multiple locations, ensuring that stock levels are accurate and up-to-date.

Each Stock Transfer will hold a list of Stock Movements.

### Stock Movements

Stock Movements track the movement of the inventory:

* when you move inventory between stock locations (via Stock Transfer)
* when you add inventory to a stock location
* when you remove inventory from a stock location
* when customers purchase products
* when customers return products

Here's the list of attributes for the Stock Movement model:

| Attribute         | Description                                                                 | Example Value       |
|-------------------|-----------------------------------------------------------------------------|---------------------|
| `stock_item_id`   | References the stock item that the movement belongs to.                     | `45`                |
| `quantity`        | The quantity by which the stock item's count on hand is changed. Positive values indicate stock being added, while negative values indicate stock being removed. | `-10`               |
| `originator_type` | The type of the originator of the stock movement. This is a polymorphic association. | `Spree::Shipment`      |
| `originator_id`   | The ID of the originator of the stock movement. This is used in conjunction with `originator_type`. | `2`                 |

Stock Movements are crucial for maintaining accurate inventory levels and for historical tracking of inventory adjustments.

## Inventory Units

As we mentioned above, back-ordered, sold, or shipped products are stored as individual `InventoryUnit` objects so they can have relevant information attached to them.

We create `InventoryUnit` objects when:

* a product is sold (they are added to the Shipment)
* a product is returned

Here's a list of attributes for the Inventory Unit model:

| Attribute         | Description                                                                 | Example Value       |
|-------------------|-----------------------------------------------------------------------------|---------------------|
| `variant_id`      | References the variant associated with the inventory unit.                 | `32`                |
| `order_id`        | References the order associated with the inventory unit.                   | `123`               |
| `shipment_id`          | References the shipment associated with the inventory unit.                   | `77`                |
| `state`           | The state of the inventory unit | `on_hand`      |

Inventory Units states are:

* `on_hand` - the inventory unit is on hand
* `backordered` - the inventory unit is backordered
* `shipped` - the inventory unit is shipped

<Note>
As we noted before, when you add new Stock Items to a Variant (eg. via Admin Panel or Platform API), the first Inventory Units to fulfill are the backordered ones.
</Note>

## Disabling inventory tracking

What if you don't need to track inventory? You can disable it for the entire application in `config/initializers/spree.rb` file which was generated during installation. Add the following line:

```ruby
Spree::Config[:track_inventory_levels] = false
```

You can also disable tracking inventory on a Variant level, by simply updating Variant `track_inventory` column to `false`, eg.

```ruby
variant.update(track_inventory: false)
```

This can also be done via the Admin Panel or Platform API.
